Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📚 Add compatibility policy to README.md #277

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

nevans
Copy link
Collaborator

@nevans nevans commented May 2, 2024

I saw a chart similar to this in ruby/openssl's README, and it seems like this is a relatively simple way to communicate our versioning.

I'll propose documentation for a slightly more detailed deprecation and compatibility policy... in a future PR.

@nevans nevans requested review from hsbt and shugo May 2, 2024 13:38
@nevans
Copy link
Collaborator Author

nevans commented May 2, 2024

@shugo @hsbt Does this match your understanding? Does it seem right to you?

Relevant to the top version in the table, #276 bumps the minimum ruby requirement.

@nevans nevans force-pushed the add-ruby-compatibility-chart-to-README.md branch from c6f14ed to ecae97a Compare May 2, 2024 13:46
@shugo
Copy link
Member

shugo commented May 2, 2024

@nevans Do you mean to maintain multiple stable branches of net-imap?

It may be enough to maintain only one branch as long as it supports all Ruby versions that are not EOL.

@nevans
Copy link
Collaborator Author

nevans commented May 3, 2024

@shugo Good question.

I had assumed that we already have an implicit commitment to maintaining older versions when their matching ruby version is still in being maintained. I figured that ruby 3.1 only bundles 0.2.x, ruby 3.2 only bundles 0.3.x, etc. For example, I was thinking of the v0.2.4, and v0.3.4.1 releases back in January. That implies some commitment to maintaining those versions, right? Hypothetically, if (prior to the ruby 3.1 EOL) a serious security issue is identified with net-imap 0.2, we would probably need to create a new 0.2.x release, right? I don't think ruby wants to bundle gems with known security issues. And it would be too disruptive to bundle 0.4.x or 0.5.x in a ruby 3.1 release (upgrading from 0.2.x to 0.5.x may include backward incompatible changes).

Also, I feel that it's easier to justify adding deprecation warnings and backward incompatible changes once a year if users aren't forced to upgrade for security or critical bugfixes. Depending on the severity, backports for three older versions might even be less expensive than the alternative?

@nevans
Copy link
Collaborator Author

nevans commented May 3, 2024

So my goal was to mirror ruby's branch maintenance policy: net-imap's branches would be in "normal maintenance" as long as their matching ruby branches are in "normal maintenance", and the same for "security maintenance".

This is slightly complicated by our release schedule, which is staggered from ruby's release schedule. For example, v0.4.0 through v0.4.8 were never bundled with any version of ruby (but v0.4.9 was). Because we're also releasing from main, this would give us four active release series rather than three.

@nevans
Copy link
Collaborator Author

nevans commented May 3, 2024

@shugo So I guess generic proposal is this:

branch net-imap ruby maintenance level
master current main (dev) new features and deprecations
vx.{y-1} current-1 current stable "normal maintenance"
vx.{y-2} current-2 previous stable "normal maintenance"
vx.{y-3} current-3 oldest stable "security maintenance"
vx.{y-4} current-4 end-of-life end of life

Currently, we have:

branch net-imap ruby maintenance level
master, ruby-3.3 0.4.x 3.3.x bugfixes, deprecations
v0.3-bugfixes, ruby-3.2 0.3.x 3.2.x backports (at our discretion)
ruby-3.1 0.2.x 3.1.x security only
none 0.1.x 3.0.x end of life

After bumping master to 0.5.0 and renaming some branches:

branch net-imap ruby maintenance level
master 0.5.x 3.4.x new features (and deprecations)
v0.4 0.4.x 3.3.x bugfix backports
v0.3 0.3.x 3.2.x bugfix backports
v0.2 0.2.x 3.1.x security only
v0.1 0.1.x 3.0.x end of life

However, to directly answer your question: although I'm willing to do some discretionary backports of bugfixes (maybe even small features) to the previous version, backporting bugfixes for two versions might be more than we should commit to. Maybe I should "downgrade" the last-stable-ruby's release series (currently "v0.3.x") to "security only"?

branch net-imap ruby maintenance level
master 0.5.x 3.4.x new features (and deprecations)
v0.4 0.4.x 3.3.x backports (at our discretion)
v0.3 0.3.x 3.2.x security only
v0.2 0.2.x 3.1.x security only
v0.1 0.1.x 3.0.x end of life

@nevans nevans force-pushed the add-ruby-compatibility-chart-to-README.md branch from ecae97a to e09388e Compare May 3, 2024 14:00
@shugo
Copy link
Member

shugo commented May 4, 2024

However, to directly answer your question: although I'm willing to do some discretionary backports of bugfixes (maybe even small features) to the previous version, backporting bugfixes for two versions might be more than we should commit to. Maybe I should "downgrade" the last-stable-ruby's release series (currently "v0.3.x") to "security only"?

I think it's enough.
Users can upgrade to newer versions if they are affected by normal bugs.

@zenspider
Copy link
Member

Sharing my own painful experience... I would recommend @shugo's advice and add that being aggressive about ONLY maintaining compatibility to currently supported versions of ruby is not only sane, but necessary.

You might be better off being generic:

  • current ruby = normal work
  • current - 1 minor = security + backports
  • current - 2 minors = security only

Aggressively dropping support for old rubies is a good thing both for maintainers and users.

@nevans nevans force-pushed the add-ruby-compatibility-chart-to-README.md branch from e09388e to 79db5b0 Compare May 8, 2024 15:03
@nevans nevans added the documentation Improvements or additions to documentation label May 19, 2024
@nevans nevans added this to the v0.6 milestone Oct 13, 2024
I saw a chart similar to this in ruby/openssl's README, and it seems
like this is a relatively simple way to communicate our basic versioning
scheme.  Documentation for a more detailed backward compatibility policy
may be added in a future PR.
@nevans nevans force-pushed the add-ruby-compatibility-chart-to-README.md branch from 79db5b0 to 0ba95f7 Compare October 30, 2024 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Development

Successfully merging this pull request may close these issues.

3 participants